/******************************************************************************
 * @file rd0ff_bsp_key_driver.h
 * @brief KEY驱动头文件
 *
 * 详细描述：
 * - 功能1：定义KEY驱动的核心数据结构和枚举类型
 * - 功能2：声明KEY初始化及按键读取函数
 * - 功能3：提供错误码定义和状态管理机制
 * - 功能4：支持操作系统环境下的延时功能
 *
 * @author 陈泳行 | R&D Dept. | Jin Dou Aerospace 金斗航天
 * @date 2025-7-8
 * @version 1.0.0
 *
 * @version_history
 * - 1.0.0 (2025-7-8): 初始版本，实现基本功能
 *
 * @note 本驱动支持操作系统环境，通过OS_DEFINE宏控制
 * @warning 按键操作前必须确保GPIO接口已正确初始化
 ******************************************************************************/
#ifndef __RD0FF_BSP_KEY_DRIVER_H
#define __RD0FF_BSP_KEY_DRIVER_H

/******************************** Includes ***********************************/
#include <stdio.h>          /* 标准输入输出函数 */
#include <stdint.h>         /* 标准整数类型定义 */
/******************************** Includes ***********************************/

/******************************** Defines  ***********************************/
/**
 * @brief 操作系统支持宏定义
 *
 * 条件编译控制：
 * - 定义OS_DEFINE：启用操作系统相关接口（如os_delay_t）
 * - 未定义OS_DEFINE：使用裸机环境实现（需用户提供延时函数）
 *
 * @note 建议在项目配置头文件中统一定义此宏
 */
//#define OS_SUPPIRTING 0
/******************************** Defines  ***********************************/

/******************************** Declare ************************************/
/**
 * @brief KEY操作返回状态码枚举
 *
 * 此枚举定义了KEY驱动所有操作可能返回的状态码，用于错误处理和调试。
 */
typedef enum
{
    KEY_DRIVER_RET_OK = 0,
    KEY_DRIVER_RET_ERROR = 1,
    KEY_DRIVER_RET_INVALID_PARAM = 2,
    KEY_DRIVER_RET_NOT_SUPPORT = 3,
    KEY_DRIVER_RET_BUSY = 4,
    KEY_DRIVER_RET_TIMEOUT = 5,
    KEY_DRIVER_RET_NO_DATA = 6,
    KEY_DRIVER_RET_OTHER = 7,
    KEY_DRIVER_RET_PRESS = 8, // 按下按键 用于read
} key_driver_ret_t;

/**
 * @brief KEY初始化状态枚举
 *
 * 此枚举定义了KEY驱动的初始化状态，用于判断驱动是否就绪。
 */
typedef enum
{
    KEY_INIT     = 1,
    KEY_NOT_INIT = 0,
} key_init_status_t;

/**
 * @brief 时基函数结构体
 *
 * 封装获取系统毫秒级时间的函数指针，用于按键消抖计时。
 */
typedef struct
{
    key_driver_ret_t (*pf_get_time_ms)(uint32_t const *time_ms);
} time_base_ms_t;

#ifdef OS_SUPPIRTING
/**
 * @brief 操作系统延时接口结构体
 *
 * 此结构体包含操作系统延时（毫秒）的函数指针。
 */
typedef struct
{
    key_driver_ret_t (*pf_os_delay_ms)(const uint32_t time_ms);
} os_delay_ms_t;
#endif

typedef struct bsp_key_driver bsp_key_driver_t;

/**
 * @brief KEY硬件接口结构体
 *
 * 封装KEY外设的GPIO端口、引脚号以及初始化和读取函数。
 */
typedef struct
{
    void                                            *GPIOx;
    uint16_t                                      GPIO_Pin;
    void                              (*pf_key_init)(void);
    uint8_t                           (*pf_key_read)(void*,
												 uint16_t);
} key_hw_t;

/**
 * @brief KEY驱动实例结构体
 *
 * 此结构体包含KEY驱动的所有接口和状态信息，是驱动操作的核心数据结构。
 */
typedef struct bsp_key_driver
{
    /*******************Target of Internal Status*********/
    key_init_status_t                          init_status;

    /*******************Target of Features****************/

    /*******************Target of IOs needed**************/
    /* The interface from Core layer			         */
    key_hw_t                                     *p_key_hw;
    time_base_ms_t                         *p_time_base_ms;
    /* The interface from OS   layer			         */
#ifdef OS_SUPPIRTING
    os_delay_ms_t                         *p_os_time_delay;
#endif
    /*******************Target of APIs********************/
} bsp_key_driver_t;

/**
 * @brief KEY驱动实例初始化函数
 *
 * 初始化KEY驱动实例，绑定硬件接口和系统函数，完成按键硬件的初始化。
 *
 * @param self KEY驱动实例指针
 * @param key_hw KEY硬件接口结构体指针
 * @param time_base_ms 时基函数结构体指针（仅OS_SUPPORTING定义时有效）
 * @param os_delay_ms OS延迟函数结构体指针（仅OS_SUPPORTING定义时有效）
 *
 * @return key_driver_ret_t 操作结果状态码
 * @retval KEY_DRIVER_RET_OK 初始化成功
 * @retval KEY_DRIVER_RET_INVALID_PARAM 参数无效
 * @retval KEY_DRIVER_RET_ERROR 初始化失败
 */
key_driver_ret_t key_driver_inst(  bsp_key_driver_t *self,
                                   key_hw_t       *key_hw
 #ifdef OS_SUPPIRTING
							,time_base_ms_t  *time_base_ms
							 ,os_delay_ms_t  *os_delay_ms
#endif
                                                          );

#endif // END __RD0FF_BSP_KEY_DRIVER_H


